Lua utility module Diary
This module provides functions to create and manage diaries.
It maintains diary definitions and entries through all levels and hubs. Each diary is accessed by the object that was used to create it.
Example usage:
local CustomDiary = require("Engine.CustomDiary") --This function creates a diary from the DiarySetup.lua template file in script folder CustomDiary.ImportDiary("DiarySetup") --This method gets the diary that was created with the DIARY_ITEM object and stores it in variable diary. local diary = CustomDiary.Get(TEN.Objects.ObjID.DIARY_ITEM) --This method opens the diary on the 3rd page diary:showDiary(3)
Functions
Functions
- CustomDiary.ImportDiary(fileName)
-
Imports diary from an external file. There are different types that must be defined. (diary, background, controls, pageNumbers, notification, image, text, narration). Each of the section's arguements are the same as the functions described in this documentation.
Refer to DiarySetup.lua file for a sample script.
Parameters:
- fileName string Name of file in the script folder without extension to import the diary from.
- CustomDiary.Create(object, objectIdBg, spriteIdBg, colorBg, pos, rot, scale, alignMode, scaleMode, blendMode, alpha, pageSound, exitSound)
-
Creates a diary with extensive configuration options.
Parameters:
Parameters:
- object ObjID The pickup object that will be used to create the diary. The diary can be created using PICKUPITEMX (596-611) or DIARYITEM (986). Access the diary by selecting the item in the inventory.
- objectIdBg ObjID Object ID for the diary's sprite.
- spriteIdBg int SpriteID from the specified object for the diary's sprite.
- colorBg Color Color of diary's sprite.
- pos Vec2 X,Y position of the bar's background in screen percent (0-100).
- rot float rotation of the diary's sprite (0-360).
- scale Vec2 X,Y Scaling factor for the bar's background sprite.
- alignMode AlignMode Alignment for the diary's sprite.
- scaleMode ScaleMode Scaling for the diary's sprite.
- blendMode BlendID Blending modes for the diary's sprite.
- alpha number alpha value for the diary's sprite (0-255).
- pageSound Sound Sound to play with page turn.
- exitSound Sound Sound to play when existing the diary.
Returns:
-
CustomDiary
- CustomDiary.Get(object)
-
The function retrieves a diary by its unique object. This function is useful when you need to access or manipulate a diary that has already been created .
Parameters:
- object ObjID The pickup object that was used to create the diary (596-611,986).
Returns:
-
CustomDiary
The diary created using the object.
- CustomDiary.Delete(object)
-
The function removes a custom diary and its associated data from the system. It ensures that the diary is no longer tracked or accessible in the LevelVars.Engine.Diaries.
Please call this once a diary has served its purpose. It helps reduce the savegame size.
Parameters:
- object ObjID The pickup object that was used to create the diary (596-611,986).
- CustomDiary.Status(value)
-
The function adds the callback to enable diaries in levels. This needs to be added to every level preferably in the LevelFuncs.OnStart.
Parameters:
- value bool True enables the diaries to be activated. False would disable the diaries.
- CustomDiary:IsVisible()
-
The function checks whether the specified diary is currently visible.
Returns:
-
bool
true if the diary is visible and false if it is not.
- CustomDiary:ShowDiary(pageIndex)
-
The function displays the specified diary. Can be used to call the diary directly using volume or classic triggers.
Parameters:
- pageIndex int The page number at which diary should be opened.
- CustomDiary:GetUnlockedPageCount()
-
The function returns the number of unlocked pages in the diary.
Returns:
-
int
total number of unlocked pages in the diary.
- CustomDiary:UnlockPages(pageIndex, notification)
-
The function unlocks the specified diary up to the given page number.
This value can be overridden to lock or unlock pages as needed. A lower number can be set to restrict access to previously unlocked pages.Parameters:
- pageIndex int The page number up to which the diary should be unlocked.
- notification bool If true, and notification has been defined, a notification icon and sound will be played.
- CustomDiary:ClearPage(pageIndex)
-
The function clears the page for the diary.
Parameters:
- pageIndex int The page number to be cleared.
- CustomDiary:AddTextEntry(pageIndex, text, textPos, textOptions, textScale, textColor)
-
Adds a text entry to the specified page for the diary.
Parameters:
- pageIndex int page number to add the text entry to.
- text string Text entry to be added to the page.
- textPos Vec2 X,Y position of the text.
- textOptions DisplayStringOption alignment and effects for the text. Default: None. Please note text is automatically aligned to the LEFT
- textScale number Scale factor for the text.
- textColor Color Color of the text.
- CustomDiary:AddImageEntry(pageIndex, objectId, spriteId, color, pos, rot, scale, alignMode, scaleMode, blendMode)
-
Adds an image entry to the specified page for the diary.
Parameters:
- pageIndex int page number to add the image entry to.
- objectId ObjID Object ID for the image entry sprite.
- spriteId number SpriteID from the specified object for the image entry.
- color Color Color of image entry.
- pos Vec2 X,Y position of the image entry in screen percent (0-100).
- rot number rotation of the image entry (0-360).
- scale Vec2 X,Y Scaling factor for the image entry.
- alignMode AlignMode Alignment for the image entry.
- scaleMode ScaleMode Scaling for the image entry.
- blendMode BlendID Blending modes for the image entry.
- CustomDiary:AddNarration(pageIndex, trackName)
-
Add a narration track in the voice channel to the page. Track is played with the draw button.
Parameters:
- pageIndex int page number to add the narration track to.
- trackName string of track (without file extension) to play.
- CustomDiary:RemoveNarration(pageIndex)
-
Remove the narration track from the page of the specified diary.
Parameters:
- pageIndex int page number to remove the narration track from.
- CustomDiary:AddBackground(objectId, spriteId, color, pos, rot, scale, alignMode, scaleMode, blendMode, alpha)
-
Add a background image for the diary.
Parameters:
- objectId ObjID Object ID for the diary's background.
- spriteId number SpriteID from the specified object for the diary's background.
- color Color Color of diary's background.
- pos Vec2 X,Y position of the diary's background in screen percent (0-100).
- rot float rotation of the diary's background sprite (0-360).
- scale Vec2 X,Y Scaling factor for the diary's background.
- alignMode AlignMode Alignment for the diary's background.
- scaleMode ScaleMode Scaling for the diary's background.
- blendMode BlendID Blending modes for the diary's background.
- alpha number alpha value for the diary's background (0-255).
- CustomDiary:ClearBackground()
- Clears settings for the background for the specified diary.
- CustomDiary:CustomizeNotification(notificationTime, objectId, spriteId, color, pos, rot, scale, alignMode, scaleMode, blendMode, notificationSound)
-
Customizes the notification icon and sound for the diary.
Parameters:
- notificationTime number Time in seconds the notification icon will show on screen.
- objectId ObjID Object ID for the notification icon.
- spriteId number SpriteID from the specified object for the notification icon.
- color Color Color of notification icon.
- pos Vec2 X,Y position of the notification icon in screen percent (0-100).
- rot number rotation of the notification icon (0-360).
- scale Vec2 X,Y Scaling factor for the notification icon.
- alignMode AlignMode Alignment for the notification icon.
- scaleMode ScaleMode Scaling for the notification icon.
- blendMode BlendID Blending modes for the notification icon.
- notificationSound Sound Sound to play with notification icon.
- CustomDiary:ClearNotification()
- Clears settings for the notification system for the specified diary.
- CustomDiary:CustomizePageNumbers(pageNoType, prefix, separator, textPos, textOptions, textScale, textColor)
-
Customizes the page numbers for the diary.
Parameters:
- pageNoType int Specifies the format for page numbers (1 or 2). 1: Displays only the current page number. 2: Formats the page number as: [Prefix][CurrentPage][Separator][UnlockedPages].
- prefix string Prefix to be added for type 2 of page numbers.
- separator string Separator to be added for type 2 of page numbers.
- textPos Vec2 X,Y position of the page numbers.
- textOptions DisplayStringOption alignment and effects for the text. Default: None. Please note text is automatically aligned to the LEFT
- textScale number Scale factor for the page numbers.
- textColor Color Color of the page numbers.
- CustomDiary:ClearPageNumbers()
- Clears settings for the page numbers for the specified diary.
- CustomDiary:CustomizeControls(textPos, textOptions, textScale, textColor)
-
Customizes the controls text for the diary.
Parameters:
- textPos Vec2 X,Y position of the controls text.
- textOptions DisplayStringOption alignment and effects for the text. Default: None. Please note text is automatically aligned to the LEFT.
- textScale number Scale factor for the controls.
- textColor Color Color of the page controls.
- CustomDiary:CustomizeControlsText(string1, string2, string3, string4, separator)
-
Customizes the display text for controls for specified diary.
Parameters:
- CustomDiary:ClearControls()
- Clears settings for the specified diary's controls text.